home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / CrtGenHdlr.3 < prev    next >
Text File  |  1994-09-20  |  4KB  |  133 lines
  1.  
  2.  
  3.  
  4. Tk_CreateGenericHandlerT(k3)Library Procedures
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tk_CreateGenericHandler, Tk_DeleteGenericHandler - associate
  12.      procedure callback with all X events
  13.  
  14. SYNOPSIS
  15.      #include <tk.h>
  16.  
  17.      Tk_CreateGenericHandler(_p_r_o_c, _c_l_i_e_n_t_D_a_t_a)
  18.  
  19.      Tk_DeleteGenericHandler(_p_r_o_c, _c_l_i_e_n_t_D_a_t_a)
  20.  
  21. ARGUMENTS
  22.      Tk_GenericProc   *_p_r_o_c        (in)      Procedure to  invoke
  23.                                              whenever any X event
  24.                                              occurs    on     any
  25.                                              display.
  26.  
  27.      ClientData       _c_l_i_e_n_t_D_a_t_a   (in)      Arbitrary   one-word
  28.                                              value   to  pass  to
  29.                                              _p_r_o_c.
  30. _________________________________________________________________
  31.  
  32.  
  33. DESCRIPTION
  34.      Tk_CreateGenericHandler arranges for _p_r_o_c to be  invoked  in
  35.      the  future  whenever any X event occurs.  This mechanism is
  36.      _n_o_t intended for dispatching X events on windows managed  by
  37.      Tk  (you should use Tk_CreateEventHandler for this purpose).
  38.      Tk_CreateGenericHandler is intended for other purposes, such
  39.      as  tracing X events, monitoring events on windows not owned
  40.      by Tk, accessing X-related libraries that  were  not  origi-
  41.      nally designed for use with Tk, and so on.
  42.  
  43.      The callback to _p_r_o_c will be made  by  Tk_HandleEvent;  this
  44.      mechanism  only  works  in  programs  that  dispatch  events
  45.      through Tk_HandleEvent (or through other Tk procedures  that
  46.      call Tk_HandleEvent, such as Tk_DoOneEvent or Tk_MainLoop).
  47.  
  48.      _P_r_o_c should have arguments and result that  match  the  type
  49.      Tk_GenericProc:
  50.           typedef int Tk_GenericProc(
  51.                ClientData _c_l_i_e_n_t_D_a_t_a,
  52.                XEvent *_e_v_e_n_t_P_t_r);
  53.      The _c_l_i_e_n_t_D_a_t_a parameter to _p_r_o_c is a copy of the _c_l_i_e_n_t_D_a_t_a
  54.      argument  given to Tk_CreateGenericHandler when the callback
  55.      was created.  Typically, _c_l_i_e_n_t_D_a_t_a points to a data  struc-
  56.      ture  containing  application-specific information about how
  57.      to handle events.  _E_v_e_n_t_P_t_r is a pointer to the X event.
  58.  
  59.  
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tk_CreateGenericHandlerT(k3)Library Procedures
  71.  
  72.  
  73.  
  74.      Whenever an X event is processed by Tk_HandleEvent, _p_r_o_c  is
  75.      called.   The  return value from _p_r_o_c is normally 0.  A non-
  76.      zero return value indicates that the event is not to be han-
  77.      dled  further; that is, _p_r_o_c has done all processing that is
  78.      to be allowed for the event.
  79.  
  80.      If there are multiple generic event handlers,  each  one  is
  81.      called for each event, in the order in which they were esta-
  82.      blished.
  83.  
  84.      Tk_DeleteGenericHandler  may   be   called   to   delete   a
  85.      previously-created  generic  event handler:  it deletes each
  86.      handler it finds that matches the _p_r_o_c and _c_l_i_e_n_t_D_a_t_a  argu-
  87.      ments.      If     no     such    handler    exists,    then
  88.      Tk_DeleteGenericHandler  returns  without  doing   anything.
  89.      Although  Tk  supports  it, it's probably a bad idea to have
  90.      more than one callback with the  same  _p_r_o_c  and  _c_l_i_e_n_t_D_a_t_a
  91.      arguments.
  92.  
  93.      Establishing a generic event handler does nothing to  ensure
  94.      that the process will actually receive the X events that the
  95.      handler wants to process.  For example, it is  the  caller's
  96.      responsibility  to invoke XSelectInput to select the desired
  97.      events, if that is necessary.
  98.  
  99. KEYWORDS
  100.      bind, callback, event, handler
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129. Tk                                                              2
  130.  
  131.  
  132.  
  133.